package net.sureon.common.mail;

import java.util.EventListener;

/**
 *  This listener helps in monitoring a mail sending process. It notifies the
 *  implementor class when the process starts, if the mail for each recipient
 *  was sent out successfully and when the process ends.
 */
public interface MailListener extends EventListener {
    /**
     * Called when an Mail Processor starts processing the Mails.
     * This method is only called once after invoking
     * MailProcessor.processMail()
     *
     * @param key     The Key that identifies the task
     * @param from    The email address of the sender
     */
    void start(Object key,
        String from);

    /**
     * Called when an email is successfully sent to the
     * Mail server
     *
     * @param key     The Key that identifies the task
     * @param to  The email address of the recipient
     */
    void sendSuccessful(Object key, String to);

    /**
     * Called when an email failed to be sent to the
     * Mail server
     *
     * @param key     The Key that identifies the task
     * @param to        The email address of the recipient
     * @param exception The Exception for the failure.
     */
    void sendFailed(Object key,
        String to, Exception exception);

    /**
     * Called when an Mail Processor finishes processing the Mails.
     * This method is only called once at the end of
     * MailProcessor.processMail()
     *
     * @param key     The Key that identifies the task
     */
    void done(Object key);
}
